{"cells": [{"cell_type": "markdown", "metadata": {"collapsed": true}, "source": ["# Using the API\n", "\n", "The GIS object is the most important object when working with the ArcGIS API for Python. The GIS object represents the online GIS you are working with, be it ArcGIS Online or a Portal for ArcGIS. You use the GIS object to consume and publish GIS content and administrators may use it to manage GIS users, groups and datastores. The GIS object also includes a number of tools, including spatial analysis tools, big data analytics tools, raster analytics tools as well as helper services such as geocoding and geometry to help in your workflows."]}, {"cell_type": "markdown", "metadata": {}, "source": ["To use the GIS object, import GIS from the arcgis.gis module:"]}, {"cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": ["from arcgis.gis import GIS"]}, {"cell_type": "markdown", "metadata": {}, "source": ["To create the GIS object, we pass your profile that contains the url and your login credentials. Please replace the credentials below with that of your org. To learn more about profiles, see [here](https://developers.arcgis.com/python/guide/working-with-different-authentication-schemes/#Storing-your-credentialls-locally)."]}, {"cell_type": "markdown", "metadata": {}, "source": ["Here, we're connecting to ArcGIS Online (the default GIS used when the url is not provided) as an anonymous user:"]}, {"cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": ["gis = GIS('home')"]}, {"cell_type": "markdown", "metadata": {}, "source": ["Adding a '?' mark after an object and querying it brings up help for that object in the notebook:"]}, {"cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [], "source": ["gis?"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The notebook provides intellisense and code-completion. Typing a dot after an object and hitting tab brings up a drop-down with its properties and methods:\n", "![dropdown showing members of GIS class](http://esri.github.io/arcgis-python-api/notebooks/nbimages/01-dropdown.png)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The GIS object provides helper objects to manage the GIS resources, i.e. the users, groups, content and datastores. These helper utilities are in the form of helper objects named users, groups, content and datastores respectively. \n", "\n", "Each such helper object has similar patterns of usage: there are methods to get(), search() and create() the respective resources."]}, {"cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [], "source": ["user = gis.users.get('rxsingh')"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The ArcGIS API for Python is integrated with Jupyter Notebook to make it easy to visualize and interact with GIS resources. The user object has a rich representation that can be queried like this:"]}, {"cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [{"data": {"text/html": ["<div class=\"9item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n", "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n", "                       <a href='https://geosaurus.maps.arcgis.com/home/user.html?user=rxsingh' target='_blank'>\n", "                        <img src='' width='200' height='133' class=\"itemThumbnail\">\n", "                       </a>\n", "                    </div>\n", "\n", "                    <div class=\"item_right\" style=\"float: none; width: auto; overflow: hidden;\">\n", "                        <a href='https://geosaurus.maps.arcgis.com/home/user.html?user=rxsingh' target='_blank'><b>Rohit Singh</b>\n", "                        </a>\n", "                        <br/><br/><b>Bio</b>: \n", "                        <br/><b>First Name</b>: Rohit\n", "                        <br/><b>Last Name</b>: Singh\n", "                        <br/><b>Username</b>: rxsingh\n", "                        <br/><b>Joined</b>: July 02, 2014\n", "\n", "                    </div>\n", "                </div>\n", "                "], "text/plain": ["<User username:rxsingh>"]}, "execution_count": 9, "metadata": {}, "output_type": "execute_result"}], "source": ["user"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The resources are implemented as Python dictionaries. You can query for the resource properties using the <b><code>resource['property']</code></b> notation:"]}, {"cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [{"data": {"text/plain": ["'Rohit'"]}, "execution_count": 10, "metadata": {}, "output_type": "execute_result"}], "source": ["user['firstName']"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The properties are also available as properties on the resource object, so you can use the dot notation to access them:"]}, {"cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [{"data": {"text/plain": ["'Singh'"]}, "execution_count": 11, "metadata": {}, "output_type": "execute_result"}], "source": ["user.lastName"]}, {"cell_type": "markdown", "metadata": {}, "source": ["The resources provide methods to update(), delete() and use the object."]}, {"cell_type": "markdown", "metadata": {}, "source": ["The GIS object includes a map widget that can be used to visualize the content of your GIS as well as see the results of your analysis. Let's bring up a map of Palm Springs, CA:"]}, {"cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": ["map = gis.map(\"Palm Springs, CA\", zoomlevel=12)\n", "map"]}, {"cell_type": "markdown", "metadata": {}, "source": ["![Sample output](http://esri.github.io/arcgis-python-api/notebooks/nbimages/01-palm-springs-map.png \"(Sample output)\")"]}, {"cell_type": "markdown", "metadata": {}, "source": ["We can search for content in our GIS. Let's search for Hiking Trails in the Palm Springs region. We do that by calling gis.content.search() and for each web map or web layers that gets returned, we can display its rich representation within the notebook:"]}, {"cell_type": "code", "execution_count": 20, "metadata": {"scrolled": false}, "outputs": [{"data": {"text/html": ["<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n", "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n", "                       <a href='https://geosaurus.maps.arcgis.com/home/item.html?id=720a2248feee4c53a78351fb4ae8e016' target='_blank'>\n", "                        <img src='' width='200' height='133' class=\"itemThumbnail\">\n", "                       </a>\n", "                    </div>\n", "\n", "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n", "                        <a href='https://geosaurus.maps.arcgis.com/home/item.html?id=720a2248feee4c53a78351fb4ae8e016' target='_blank'><b>Loop3Hahn_WFL</b>\n", "                        </a>\n", "                        <br/>Hahn Loop Trail<img src='https://geosaurus.maps.arcgis.com/home/js/jsapi/esri/css/images/item_type_icons/featureshosted16.png' style=\"vertical-align:middle;\">Feature Layer Collection by kgrahamACBCI\n", "                        <br/>Last Modified: February 28, 2018\n", "                        <br/>0 comments, 4,370 views\n", "                    </div>\n", "                </div>\n", "                "], "text/plain": ["<Item title:\"Loop3Hahn_WFL\" type:Feature Layer Collection owner:kgrahamACBCI>"]}, "metadata": {}, "output_type": "display_data"}, {"data": {"text/html": ["<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n", "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n", "                       <a href='https://geosaurus.maps.arcgis.com/home/item.html?id=fbe6713d6aa94e0fb4fec08952949119' target='_blank'>\n", "                        <img src='' width='200' height='133' class=\"itemThumbnail\">\n", "                       </a>\n", "                    </div>\n", "\n", "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n", "                        <a href='https://geosaurus.maps.arcgis.com/home/item.html?id=fbe6713d6aa94e0fb4fec08952949119' target='_blank'><b>Palm Springs Trails</b>\n", "                        </a>\n", "                        <br/>Trails in the Palm Springs area affected by the BLM - Agua Caliente land exchange<img src='https://geosaurus.maps.arcgis.com/home/js/jsapi/esri/css/images/item_type_icons/featureshosted16.png' style=\"vertical-align:middle;\">Feature Layer Collection by paniello_geodesign\n", "                        <br/>Last Modified: March 13, 2015\n", "                        <br/>0 comments, 406 views\n", "                    </div>\n", "                </div>\n", "                "], "text/plain": ["<Item title:\"Palm Springs Trails\" type:Feature Layer Collection owner:paniello_geodesign>"]}, "metadata": {}, "output_type": "display_data"}, {"data": {"text/html": ["<div class=\"item_container\" style=\"height: auto; overflow: hidden; border: 1px solid #cfcfcf; border-radius: 2px; background: #f6fafa; line-height: 1.21429em; padding: 10px;\">\n", "                    <div class=\"item_left\" style=\"width: 210px; float: left;\">\n", "                       <a href='https://geosaurus.maps.arcgis.com/home/item.html?id=780e49f2e5084e91b517e597474a341b' target='_blank'>\n", "                        <img src='' width='200' height='133' class=\"itemThumbnail\">\n", "                       </a>\n", "                    </div>\n", "\n", "                    <div class=\"item_right\"     style=\"float: none; width: auto; overflow: hidden;\">\n", "                        <a href='https://geosaurus.maps.arcgis.com/home/item.html?id=780e49f2e5084e91b517e597474a341b' target='_blank'><b>Loop2WestFork_WFL</b>\n", "                        </a>\n", "                        <br/>West Fork Loop<img src='https://geosaurus.maps.arcgis.com/home/js/jsapi/esri/css/images/item_type_icons/featureshosted16.png' style=\"vertical-align:middle;\">Feature Layer Collection by kgrahamACBCI\n", "                        <br/>Last Modified: February 28, 2018\n", "                        <br/>0 comments, 4,951 views\n", "                    </div>\n", "                </div>\n", "                "], "text/plain": ["<Item title:\"Loop2WestFork_WFL\" type:Feature Layer Collection owner:kgrahamACBCI>"]}, "metadata": {}, "output_type": "display_data"}], "source": ["from IPython.display import display\n", "\n", "items = gis.content.search('Palm Springs Trails', item_type=\"Feature Layer\", outside_org=True)\n", "for item in items[:3]:\n", "    display(item)"]}, {"cell_type": "markdown", "metadata": {}, "source": ["We can add the returned web layers to our map. To add the \u2018Palm Springs Trails\u2019 layer returned above, we call map.add_layer() and pass in the corresponding layer. This adds the layer to the map widget we created above."]}, {"cell_type": "code", "execution_count": 25, "metadata": {}, "outputs": [], "source": ["map.add_layer(items[1].layers[0])"]}], "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.2"}}, "nbformat": 4, "nbformat_minor": 1}